Aminet 12/Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso/Aminet/dev/lang/HeliOS4.lha/helios_demo_disk4/docs/userinterface/IncludeFiles.doc

Text File | 1995-03-20 | 16.6 KB | 501 lines

*************
Include Files
*************

HeliOS V6 has an ultra-fast and flexible include symbol search facility,
allowing symbolic values from Amiga include files as well as pre-defined
user symbol bases to be accessed from within HeliOS programs.

HeliOS "includes" store symbolic names and associated numeric values in a
special pre-encoded file format designed to allow extremely fast access.

The include files are held memory resident for fast processing.

It is very easy to generate new custom include files for any individual
application, or to edit existing files: building sets of pre-processed
symbols is simple and quick.

Speed of access was the main criterion when creating the HeliOS include
system, since compilation speed depends heavily on the rapidity of symbol
searches.  Symbol searches are VERY fast, and huge symbol bases can be
conveniently accessed with virtually negligable response delay.

Without prejudice to the all-important criterion of speed, some measure
of data compression has also been achieved as an additional bonus.

There is no limit on symbol base or include file size.

HeliOS can load and access two separate pre-processed include files
simultaneously at any time, and a very complete set of include file
functions are provided.

For example, you can:

 * Include symbolic values "transparently" in HeliOS programs.

 * Look-up and display individual symbol values from the symbol base.

 * Add individual symbols to the symbol base.

 * Delete individual symbols from the symbol base.

 * Delete a whole symbol base.

 * Display/print/save expanded ASCII format symbol listings.

 * Process symbol listing files to (re)generate new include files.

 * Use two simultaneously-on-line symbol reference include files.

 * Load either one, two or no includes files automatically at startup.

 * Load and/or change either of the two include files at any time.

 * Load and/or change either of the two include files within programs.

 * Switch on/off symbol searches from either/both of loaded includes.

 * Switch within programs between 16-bit and 32-bit include values.


*****************************************
Setting up and testing the include system
*****************************************

The Interpreter window has a menu called "Includes" which contains all the
include manipulation tools.

The Editor window has a few include symbol manipulation functions in the
menu called "Toolkit", but all major include operations should be carried
out from within the Interpreter window.

The first step is to load or create an include file to work with while you
experiment with these tools.

The system may initially have no include files loaded, so try using the
menu option to add a few symbols to the user include: a new user include
file will automatically be created to hold your new symbols.  If you then
save your new user include file, you can use this as the basis for a few
simple trials to familiarise yourself with the HeliOS include system.

Once you have created your own user include file, you can tell the system
how to access it and have the file loaded automatically at startup time.
Otherwise you can load any include file at any time from a menu option.

See the file "InitialSetup.doc" for instructions on how to set up startup
default include files.

An include file containing Amiga OS symbolic values is provided ready for
use: you might wish to use the "Include" menu options in the Interpreter
window to load this file as the current Amiga include file.

You can also tell the HeliOS system to autoload this file as the default
Amiga include file if you like: if you do this you will in future always
have all the Amiga include symbols "on-line".

Note that each time you add a symbol to the user include, the system has
to insert this new symbol into the existing list and sort the list.  With
a small include file this process is instantaneous, but if you try adding
new symbols to the large Amiga include file there will be a slight delay
while the list is re-sorted.

To try out the HeliOS include system at its simplest level, try using the
menu option to add a few new user symbols: note that you can use "$" and
"%"" for hex and binary numbers, or no prefix for decimal numbers.

You can now use the menu option to get the values of any of your symbols.

Your new symbol names can also be entered at the command line or in your
program source code. The HeliOS interpreter will recognise a symbolic name
and translate it into a (double) 32-bit number or (normal) 16-bit number,
depending on the use of the words LONGINCLUDE and WORDINCLUDE for the
purposes of program compilation and execution.

By default, at startup, each of the include symbols is translated as a
32-bit number as far as the HeliOS interpreter is concerned.

The word WORDINCLUDE switches over to 16-bit include translation, which
will remain in force until you use the word LONGINCLUDE or you restart
the system.

Try making a new symbol called MYSYMBOL, giving it the value 10.

Now try typing "MYNEWSYMBOL .S" at the command line.

You will notice that the 32-bit number 10. is now on the stack, just as if
you had origianlly typed "10. .S" rather than "MYNEWSYMBOL .S".

Type "SP!" to clear the stack.

Now try typing "WORDINCLUDE" at the command line, followed by the previous
"MYNEWSYMBOL .S".

You will notice that a 16-bit number 10 is now on the stack, just as if
you had origianlly typed "10 .S" rather than "MYNEWSYMBOL .S".


*********
Important
*********

 1. Include symbols are case sensitive, unlike HeliOS words, so take care.

 2. Include symbols are ALWAYS translated into 32-bit numbers or 16-bit
    numbers according to the use of WORDINCLUDE and LONGINCLUDE.

    Remember that the default is 32-bit, and make sure that your software
    clearly and explicitly sets include symbol length correctly before
    using include symbolic values.

 3. Although include symbols may be translated into DOUBLE 32-bit numbers,
    you do NOT (and MUST NOT) use a "." to signify a double number when
    entering a symbol value when defining a symbol.

    This is NOT like entering a number in HeliOS code - just enter the
    numeric value with no ".".


*****************
How includes work
*****************

As mentioned above, there is the facility to manage two include files on-
line at any one time, and these two files have slightly different useage.


*********************************
1st include file = "User include"
*********************************

This file is intended to to be a flexible and easily configurable resource
for symbolic values you wish to create for individual programs.

You can easily:

 * Add a new symbol
 * Remove any symbol
 * View symbol values
 * Create a current listing
 * Load a new file
 * Save the current file
 * Switch on/off startup autoload
 * Set startup autoload default file
 * Choose whether or not this include file will be used in symbol searches
 * Close down the include file and free memory resources


**********************************
2nd include file = "Amiga include"
**********************************

This file is intended to to be a relatively fixed "large" symbol resource
like the CBM include files.  We call this the "Amiga" include because it
is intended to store all the Amiga OS include symbolic values.

You can:

 * View symbol values
 * Load a new file
 * Switch on/off startup autoload
 * Set startup autoload default file
 * Choose whether or not this include file will be used in symbol searches


***********
File format
***********

Both "User" and "Amiga" include files have identical file formats.

This means that you can:

 * Load any HeliOS include file in either status.

 * Operate on any include file with the more powerful "User" include tools.
   e.g. You can change individual symbols in the file you usually use as
        the "Amiga" include by first loading it in as the "User" include.

Although the file format is "encoded", you have a wide range of facilities
for editing HeliOS include files.

You can use the "Display current user include" function to generate an
ASCII listing of an include file so that you can see just what symbols are
in there.  This listing can be passed into the "OUT" editor.

This ASCII listing can be freely edited and then "recompiled" into a new
HeliOS include file using the "Convert equ file to include" function.

You can also edit individual symbols directly "on-line" and re-save the
edited include file.

This gives you a virtually unlimited scope for creating/editing include
symbol bases.  You can either generate a new include file from an ASCII
listing, or simply create new symbols individually as you go.


************************************
Converting ASCII to "HeliOS Include"
************************************

The "Convert equ file to include" function allows you to process any ASCII
"equate" listing into a HeliOS include file.

The ASCII file parser is very flexible, but there obviously must be some
constraints.

The ASCII listing must be in the following format:

 1. Each line must start with the first letter of the symbol name
 2. Each line must end with the numeric symbol value
 3. Hex values must be prefixed by "$"
 4. Binary values must be prefixed by "%"
 5. All other values will be treated as decimal
 6. Negative values should have "$" or "%" identifier BEFORE the "-" sign

These are all valid lines:

MYSYMBOL equ $0000001
MYSYMBOL $0000001
MYSYMBOL                           %100100
MYSYMBOL EQUALS     157
MYSYMBOL any old thing can go in here if you like $12
MYSYMBOL 3
MYSYMBOL equ    $-C

The important thing is that the first and last items are the symbol and
the numeric value.

You can use this conversion facility to import "equ" files from other
sources and include these "foreign" symbols in HeliOS code.

Remember that all include symbols are always case sensitive.


************************************
Interpretation and search precedence
************************************

If you want to make best use of the software for fast compilation it helps
to know what is happening internally.

Always remember that using symbolic values from the include files will
slow down program compilation to some small extent.  Here is why:

The interpreter carries out searches in the following order as it parses
the input stream:

  1. It gets the next space-delimited ASCII word from the input stream

  2. It searches the HeliOS vocabulary for a matching word

.....if this fails

  3. It tries to interpret the word as a number using the current base

.....if this fails

  4. It tries to find the word in the "User" include file only if

      a. If there is a "User" include loaded
      b. If the "User" include search function is switched on

.....if this fails

  5. It tries to find the word in the "Amiga" include file only if

      a. If there is an "Amiga" include loaded
      b. If the "Amiga" include search function is switched on

.....if all these fail you have an error!


This means that:

 1. A HeliOS constant with the same mame as an include symbol will take
    precedence and will be accepted first and fastest by the interpreter.

 2. A "User include" symbol with the same mame as an "Amiga include" symbol
    will take precedence and will be accepted first by the interpreter.


**********************************************
Pros and cons of various numeric entry methods
**********************************************

You can enter numbers:

 1. As coded HeliOS constants (or variables)
 2. As include file symbols
 3. Directly as numbers

Note that:

*****************************************
Coded "Constants" are fastest.....but....
*****************************************

The fastest compilation will always result from storing numeric values as
coded HeliOS constants.

This method has these advantages:

 1. It is fastest

 2. It uses less dictionary space in HeliOS (unlike traditional Forth)

 3. You can access numbers by convenient and less error prone symbolic names

 4. You can use 8-bit, 16-bit or 32-bit values

 5. Source code is more comprehensible using symbols

 6. Global symbol changes are easy and convenient

 7. Symbols created in this way are not case sensitive

It also has these disadvantages:

 1. It is more involved to set up

 2. It is not "realistic" to access all the CBM include symbols in this way!

 3. It is less flexible.

 4. Symbols are less easily portable between programs.

 5. Importing symbol bases from other sources is difficult/inconvenient

 6. These symbols names not being case sensitive may actually be a problem


***************************************************
Hard-coded "Numbers" are nearly as fast.....but....
***************************************************

Using a "hard coded" number is nearly as good in terms of speed but can be
tedious and can tend to introduce errors.

In fact HeliOS provides an include symbol "look-up" facility so that you
can easily get numeric values for include symbols if you want to enter
a numeric value directly.

This method has these advantages:

 1. It is fast

 2. It is easy when experimenting with code development

 3. You do not need to remember symbol names


It also has these disadvantages:

 1. It can be rather error prone

 2. Translating values from external symbolic sources is tedious

 3. Source code is less comprehensible

 4. Global symbol changes are difficult


****************************************************
Include symbols may not be quite so fast.....but....
****************************************************

Using includes is very convenient and flexible, allows easy portability of
symbols between programs (and even from other programming environments),
and has good error protection since symbols are precise and case sensitive.


This method has these advantages:

 1. It is fast enough for most purposes

 2. You can access numbers by convenient and less error prone symbolic names

 3. Source code is more comprehensible using symbols

 4. Symbol bases can easily be imported/exported

 5. All symbols can be easily output as an alphabetic listing

 6. Global symbol changes are easy

 7. Case sensitivity is enforced, which may be helpful

It also has these disadvantages:

 1. It has the slowest compilation of the methods under discussion

 2. Symbols and source code are not fully integrated

 3. All symbols are translated only as 32-bit or 16-bit numbers

 4. Case sensitivity is enforced, which may be a nuisance

 5. Careless use of WORDINCLUDE and LONGINCLUDE can cause problems

Although we have said they are the slowest option, for general use the
include symbol searches are quite sufficiently quick.

You may choose to employ include file symbols for the majority of cases
where speed of compilation is not absolutely vital.

Include files are certainly the most flexible method of accessing numeric
and symbolic values provided that:

 a. The small compilation speed penalty is tolerable

 b. The enforced 32-bit or 16-bit number translation is appropriate

 c. You take care to use WORDINCLUDE and LONGINCLUDE carefully

****************************
Compilation versus execution
****************************

It may be pointed out that the above speed considerations only relate to
the process of interpretation and compilation of the dictionary.

This means that the final program will run at the same speed whatever
method you use.

See the file "HeliOSCompilation.doc" for a detailed discussion of how
the compilation process works, and the pros and cons of the various ways
of using symbolic values.


*****************************************************************
Overview of the effects of using "include" versus "coded" symbols
*****************************************************************

The initial processes of interpretation and compilation will be affected
to some extent by the methods of symbol definition which you employ.

Compilation will be fastest when using HeliOS constants for symbolic values,
and the symbol names will be stored in the HeliOS vocabulary list.

HeliOS coded constants may be conveniently defined as 8-bit, 16-bit or
32-bit values.

Include symbol searches will slightly increase compilation times, but you
may well find any compilation speed differences insignificant on most
programs since the HeliOS compiler is very quick anyway.

Include symbols are translated into pure 32-bit or 16-bit numbers during
the process of compilation, so they do not affect the HeliOS vocabulary
at all.

Include symbols are translated during the process of compilation, so the
include file plays no part in program execution and is not needed after
program compilation.

Include symbols are all translated automatically as 32-bit or 16-bit
numbers depending on the use of WORDINCLUDE and LONGINCLUDE.

Final program execution will be totally unaffected by methods of symbol
definition.

*****************************************************************************